---
sidebar_label: Webhook Events
---

# Webhook Events

Webhook events are one-way events sent to your app over HTTP to notify you when an event occured. Unlike events that are [sent over Gateway connections](/docs/events/gateway), events sent over webhooks are not realtime or guaranteed to be in order.

While [incoming webhooks](/docs/resources/webhook) are triggered by an external service, webhook events (i.e. outgoing webhooks) are triggered by events happening in Discord. This means your app will need to set up a public URL where you can receive HTTP events, which is detailed in the [preparing for events](/docs/events/webhook-events#preparing-for-events) section.

## Subscribing to Events

To configure webhook events, you'll need to configure your URL and select the events you want your app to receive.

:::info
The steps below walk through subscribing using the developer portal. If you prefer to use the API, you can call [Edit Current Application](/docs/resources/application#edit-current-application).
:::

In your [app's settings](https://discord.com/developers/applications), navigate to the **Webhooks** page from the left-hand sidebar then complete the following:

1. Under **Endpoint**, add a public URL that is set up to receive and acknowledge webhook events. Details about setting up a Webhook Events URL is in the [preparing for events](/docs/events/webhook-events#preparing-for-events) section.
2. Enable Events by clicking the toggle in the **Events** section.
3. Select the [webhook events](/docs/events/webhook-events#event-types) you want your app to receive.
4. Click **Save Changes**.

If your URL is successfully verified, your app should begin receiving the events you selected.

## Preparing for Events

To receive webhook events, you'll need to configure your app's **Webhook Event URL** in your app's settings.

### Configuring a Webhook Events URL

A **Webhook Events URL** is a public endpoint for your app where Discord can send your app HTTP-based events. If your app is using [Gateway events](/docs/events/gateway), you don't need to configure a Webhook Events URL.

#### Setting Up an Endpoint

Before you can add a Webhook Events URL to your app, your endpoint must be prepared for two things ahead of time:

1. Acknowledging `PING` events from Discord
2. Validate security-related request headers (`X-Signature-Ed25519` and `X-Signature-Timestamp`)

If either of these are not complete, your Webhook Events URL will not be validated. Details on acknowledging PING events and validating security-related headers are below.

###### Acknowledging PING requests

When adding your Webhook Events URL, Discord will send a `POST` request with a `PING` payload with a `type: 0` to your endpoint. Your app is expected to acknowledge the request by returning a `204` response with an empty body.

:::info
You must provide a valid `Content-Type` when responding to `PING`s. See [here](/docs/reference#http-api) for further information.
:::

<Collapsible title="Responding to PING Requests" description="Code example for acknowledging PING events" icon="code">
To properly acknowledge a `PING` payload, return a `204` response with no body:

```py
@app.route('/', methods=['POST'])
def my_command():
    if request.json["type"] == 0:
        return Response(status=204)
```
</Collapsible> 

###### Validating Security Request Headers

To receive events via HTTP, there are some security steps you **must** take before your app is eligible to receive requests.

Each webhook is sent with the following headers:

-   `X-Signature-Ed25519` as a signature
-   `X-Signature-Timestamp` as a timestamp

Using your favorite security library, you **must validate the request each time you receive an event**. If the signature fails validation, your app should respond with a `401` error code. Code examples of validating security headers is in the [Interactions documentation](/docs/interactions/overview#setting-up-an-endpoint-validating-security-request-headers).

In addition to ensuring your app validates security-related request headers at the time of saving your endpoint, Discord will also perform automated, routine security checks against your endpoint, including purposefully sending you invalid signatures. If you fail the validation, we will remove your Webhook Events URL and alert you via email and System DM.

We recommend checking out our [Community Resources](/docs/developer-tools/community-resources) and the libraries found there.

#### Adding an Webhook Events Endpoint URL

After you have a public endpoint to use as your app's Event Webhooks URL, you can add it to your app by going to your [app's settings](https://discord.com/developers/applications).

On the **Webhooks** page, look for the **Endpoint URL** field. Paste your public URL that is set up to acknowledge `PING` messages and correctly handles security-related signature headers.

After you configure your Webhook Events URL, you can [enable and subscribe to events](/docs/events/webhook-events#subscribing-to-events) on the same page.


## Responding to Events

When your Webhook Event URL receives a webhook event, your app should respond with a `204` status code with no body **within 3 seconds** to acknowledge that your app successfully received it. If your app doesn't respond to the webhook event, Discord will retry sending it several times using exponential backoff for up to 10 minutes.

If your app fails to respond too often, Discord will stop sending you webhook events and notify you via email.

## Webhook Event Payloads

Webhook events are wrapped in an outer payload, with an inner `event` object.

### Payload Structure

Structure of the outer webhook payload

| Field          | Type                                                               | Description                                                    |
|----------------|--------------------------------------------------------------------|----------------------------------------------------------------|
| version        | integer                                                            | Version scheme for the webhook event. Currently always `1`     |
| application_id | snowflake                                                          | ID of your app                                                 |
| type           | [webhook type](/docs/events/webhook-events#webhook-types)          | Type of webhook, either `0` for PING or `1` for webhook events |
| event?         | [event body](/docs/events/webhook-events#event-body-object) object | Event data payload                                             |

#### Webhook Types

| Type  | Value | Description                                                                                             |
|-------|-------|---------------------------------------------------------------------------------------------------------|
| PING  | `0`   | PING event sent to verify your Webhook Event URL is active                                              |
| Event | `1`   | Webhook event (details for event in [event body](/docs/events/webhook-events#event-body-object) object) |

#### Event Body Object

The event body contains high-level data about the event, like the type and time it was triggered.

The inner `data` object contains information specific to the [event type](/docs/events/webhook-events#event-types).

| Field     | Type   | Description                                                                                        |
|-----------|--------|----------------------------------------------------------------------------------------------------|
| type      | string | [Event type](/docs/events/webhook-events#event-types)                                              |
| timestamp | string | Timestamp of when the event occurred in [ISO8601 format](/docs/reference#iso8601-datetime)         |
| data?     | object | Data for the event. The shape depends on the [event type](/docs/events/webhook-events#event-types) |


## Event Types

The table below includes the different webhook event types your app can subscribe to.

The "Value" column corresponds to the event's `type` field value in the [event body object](/docs/events/webhook-events#event-body-object).

| Name                                                                                 | Value                        | Description                                                               |
|--------------------------------------------------------------------------------------|------------------------------|---------------------------------------------------------------------------|
| [Application Authorized](/docs/events/webhook-events#application-authorized)         | `APPLICATION_AUTHORIZED`     | Sent when an app was authorized by a user to a server or their account    |
| [Application Deauthorized](/docs/events/webhook-events#application-deauthorized)     | `APPLICATION_DEAUTHORIZED`   | Sent when an app was deauthorized by a user                               |
| [Entitlement Create](/docs/events/webhook-events#entitlement-create)                 | `ENTITLEMENT_CREATE`         | Entitlement was created                                                   |
| [Quest User Enrollment](/docs/events/webhook-events#quest-user-enrollment)           | `QUEST_USER_ENROLLMENT`      | User was added to a Quest (currently unavailable)                         |
| [Lobby Message Create](/docs/events/webhook-events#lobby-message-create)             | `LOBBY_MESSAGE_CREATE`       | Sent when a message is created in a lobby                                 |
| [Lobby Message Update](/docs/events/webhook-events#lobby-message-update)             | `LOBBY_MESSAGE_UPDATE`       | Sent when a message is updated in a lobby                                 |
| [Lobby Message Delete](/docs/events/webhook-events#lobby-message-delete)             | `LOBBY_MESSAGE_DELETE`       | Sent when a message is deleted from a lobby                               |
| [Game Direct Message Create](/docs/events/webhook-events#game-direct-message-create) | `GAME_DIRECT_MESSAGE_CREATE` | Sent when a direct message is created during an active Social SDK session |
| [Game Direct Message Update](/docs/events/webhook-events#game-direct-message-update) | `GAME_DIRECT_MESSAGE_UPDATE` | Sent when a direct message is updated during an active Social SDK session |
| [Game Direct Message Delete](/docs/events/webhook-events#game-direct-message-delete) | `GAME_DIRECT_MESSAGE_DELETE` | Sent when a direct message is deleted during an active Social SDK session |

#### Application Authorized

`APPLICATION_AUTHORIZED` is sent when the app is added to a server or user account.

###### Application Authorized Structure

| Field             | Type                                                               | Description                                                                                                                                                                                                            |
|-------------------|--------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| integration_type? | integer                                                            | [Installation context](/docs/resources/application#application-object-application-integration-types) for the authorization. Either guild (`0`) if installed to a server or user (`1`) if installed to a user's account |
| user              | [user object](/docs/resources/user#user-object-user-structure)     | User who authorized the app                                                                                                                                                                                            |
| scopes            | array of strings                                                   | List of [scopes](/docs/topics/oauth2#shared-resources-oauth2-scopes) the user authorized                                                                                                                               |
| guild?            | [guild object](/docs/resources/guild#guild-object-guild-structure) | Server which app was authorized for (when integration type is `0`)                                                                                                                                                     |


###### Application Authorized Example

```json
{
  "version": 1,
  "application_id": "1234560123453231555",
  "type": 1,
  "event": {
    "type": "APPLICATION_AUTHORIZED",
    "timestamp": "2024-10-18T14:42:53.064834",
    "data": {
      "integration_type": 1,
      "scopes": [
        "applications.commands"
      ],
      "user": {
        // user data
      }
    }
  }
}
```

#### Application Deauthorized

`APPLICATION_DEAUTHORIZED` is sent when the app is deauthorized by a user.

###### Application Deauthorized Structure

| Field | Type                                                           | Description                   |
|-------|----------------------------------------------------------------|-------------------------------|
| user  | [user object](/docs/resources/user#user-object-user-structure) | User who deauthorized the app |

###### Application Deauthorized Example

```json
{
  "version": 1,
  "application_id": "1234560123453231555",
  "type": 1,
  "event": {
    "type": "APPLICATION_DEAUTHORIZED",
    "timestamp": "2024-10-18T14:42:53.064834",
    "data": {
      "user": {
        // user data
      }
    }
  }
}
```

#### Entitlement Create

`ENTITLEMENT_CREATE` is sent when an [entitlement](/docs/resources/entitlement) is created when a user purchases or is otherwise granted one of your app's SKUs. Refer to the [Monetization documentation](/docs/monetization/overview) for details.

###### Entitlement Create Structure

The inner payload is an [entitlement](/docs/resources/entitlement#entitlement-object) object.

###### Entitlement Create Example

```json
{
  "version": 1,
  "application_id": "1234560123453231555",
  "type": 1,
  "event": {
    "type": "ENTITLEMENT_CREATE",
    "timestamp": "2024-10-18T18:41:21.109604",
    "data": {
      "application_id": "1234560123453231555",
      "consumed": false,
      "deleted": false,
      "gift_code_flags": 0,
      "id": "1234505980407808808",
      "promotion_id": null,
      "sku_id": "123489045643835123",
      "type": 4,
      "user_id": "111178765189277770"
    }
  }
}
```

#### Quest User Enrollment

:::warn
This event cannot be received by apps at this time. It's documented because it appears on the Webhooks settings page.
:::

`QUEST_USER_ENROLLMENT` is sent when a user is added to a Quest on Discord.

#### Lobby Message Create

`LOBBY_MESSAGE_CREATE` is sent when a message is created in a lobby.

###### Lobby Message Create Structure

The inner payload is a [lobby message object](/docs/events/webhook-events#lobby-message-object).

###### Lobby Message Create Example

```json
{
  "version": 1,
  "application_id": "1234567765431056709",
  "type": 1,
  "event": {
    "type": "LOBBY_MESSAGE_CREATE",
    "timestamp": "2024-10-18T18:41:21.109604",
    "data": {
      "id": "1397729799727878254",
      "type": 0,
      "content": "welcome to the party!",
      "lobby_id": "1397729744753266719",
      "channel_id": "1397729744753266719",
      "author": {
        // user data
      },
      "flags": 65536,
      "application_id": "1234567765431056709"
    }
  }
}
```

#### Lobby Message Update

`LOBBY_MESSAGE_UPDATE` is sent when a message is updated in a lobby.

###### Lobby Message Update Structure

The inner payload is a [lobby message object](/docs/events/webhook-events#lobby-message-object) with additional fields for message updates.

###### Lobby Message Update Example

```json
{
  "version": 1,
  "application_id": "1234567765431056709",
  "type": 1,
  "event": {
    "type": "LOBBY_MESSAGE_UPDATE",
    "timestamp": "2025-08-05T20:39:19.587872",
    "data": {
      "id": "1402390388030832792",
      "type": 0,
      "content": "noice",
      "lobby_id": "1402385687281537066",
      "channel_id": "1402389638311841883",
      "author": {
        // user data
      },
      "edited_timestamp": "2025-08-05T20:39:19.557970+00:00",
      "flags": 0,
      "timestamp": "2025-08-05T20:38:43.660000+00:00"
    }
  }
}
```

#### Lobby Message Delete

`LOBBY_MESSAGE_DELETE` is sent when a message is deleted from a lobby.

###### Lobby Message Delete Structure

| Field    | Type      | Description                                   |
|----------|-----------|-----------------------------------------------|
| id       | snowflake | ID of the deleted message                     |
| lobby_id | snowflake | ID of the lobby where the message was deleted |

###### Lobby Message Delete Example

```json
{
  "version": 1,
  "application_id": "1234567765431056709",
  "type": 1,
  "event": {
    "type": "LOBBY_MESSAGE_DELETE",
    "timestamp": "2025-08-05T21:44:09.412957",
    "data": {
      "id": "1402406637632884857",
      "lobby_id": "1402399883394285659"
    }
  }
}
```

#### Game Direct Message Create

`GAME_DIRECT_MESSAGE_CREATE` is sent when a direct message is created while at least one user has an active Social SDK session.

###### Game Direct Message Create Structure

The inner payload is a [message object](/docs/events/webhook-events#message-object) or [passthrough message object](/docs/events/webhook-events#passthrough-message-object).

###### Game Direct Message Create Example

```json
{
  "version": 1,
  "application_id": "1234567765431056709",
  "type": 1,
  "event": {
    "type": "GAME_DIRECT_MESSAGE_CREATE",
    "timestamp": "2025-08-14T18:09:38.063234",
    "data": {
      "id": "1405614357781545021",
      "type": 0,
      "content": "get in friend, we're going raiding",
      "channel_id": "1405604229820715098",
      "author": {
        // user data
      },
      "timestamp": "2025-08-14T18:09:37.947000+00:00",
      "application_id": "1234567765431056709",
      "attachments": []
    }
  }
}
```

#### Game Direct Message Update

`GAME_DIRECT_MESSAGE_UPDATE` is sent when a direct message is updated while at least one user has an active Social SDK session.

###### Game Direct Message Update Structure

The inner payload is a [message object](/docs/events/webhook-events#message-object) or [passthrough message object](/docs/events/webhook-events#passthrough-message-object).

###### Game Direct Message Update Example

```json
{
  "version": 1,
  "application_id": "1234567765431056709",
  "type": 1,
  "event": {
    "type": "GAME_DIRECT_MESSAGE_UPDATE",
    "timestamp": "2025-08-14T16:44:31.847073",
    "data": {
      "id": "1405591838810706081",
      "content": "almost ready to queue?",
      "channel_id": "1404960877324533784",
      "author": {
        // user data
      },
      "recipient_id": "1404960877324533784"
    }
  }
}
```

#### Game Direct Message Delete

`GAME_DIRECT_MESSAGE_DELETE` is sent when a direct message is deleted while at least one user has an active Social SDK session.

###### Game Direct Message Delete Structure

The inner payload is a [message object](/docs/events/webhook-events#message-object) or [passthrough message object](/docs/events/webhook-events#passthrough-message-object).

###### Game Direct Message Delete Example

```json
{
  "version": 1,
  "application_id": "1234567765431056709",
  "type": 1,
  "event": {
    "type": "GAME_DIRECT_MESSAGE_DELETE",
    "timestamp": "2025-08-20T17:01:50.099204",
    "data": {
      "id": "1407771600643686503",
      "type": 0,
      "content": "cant make it in time",
      "channel_id": "1405604229820715098",
      "author": {
        // user data
      },
      "timestamp": "2025-08-20T17:01:44.725000+00:00",
      "flags": 0,
      "attachments": [],
      "components": []
    }
  }
}
```

## Social SDK Message Objects

Discord Social SDK utilizes specialized message objects for lobby and direct message events that occur during active game sessions. These objects extend or modify the standard Discord message structure to support communication features.

- [Lobby messages](/docs/events/webhook-events#lobby-message-object) include lobby-specific fields like `lobby_id`
- [Standard Discord messages](/docs/events/webhook-events#message-object) in SDK contexts may include additional fields
- [Passthrough messages](/docs/events/webhook-events#passthrough-message-object) are used for communication between provisional accounts

These objects are used in the webhook events `LOBBY_MESSAGE_*` and `GAME_DIRECT_MESSAGE_*` depending on the messaging context.

### Lobby Message Object

Represents a message sent in a lobby or [Linked Channel](/docs/discord-social-sdk/development-guides/linked-channels).

###### Lobby Message Structure

| Field           | Type                                                           | Description                                                                                                                             |
|-----------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| id              | snowflake                                                      | ID of the message                                                                                                                       |
| type            | integer                                                        | [Type of message](/docs/resources/message#message-object-message-types)                                                                 |
| content         | string                                                         | Contents of the message                                                                                                                 |
| lobby_id        | snowflake                                                      | ID of the lobby where the message was sent                                                                                              |
| channel_id      | snowflake                                                      | ID of the channel the message was sent in                                                                                               |
| author          | [user object](/docs/resources/user#user-object-user-structure) | Author of the message                                                                                                                   |
| metadata?       | object                                                         | Additional metadata for the message (key-value pairs)                                                                                   |
| flags           | integer                                                        | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
| application_id? | snowflake                                                      | ID of the application (only present during active Social SDK sessions)                                                                  |

### Message Object

Standard [Message Object](/docs/resources/message#messages-resource) with additional fields.

###### Additional Fields

| Field     | Type                                                     | Description                                                                             |
|-----------|----------------------------------------------------------|-----------------------------------------------------------------------------------------|
| lobby_id? | snowflake                                                | ID of the lobby where the message was created (only present in Linked Channel messages) |
| channel   | [channel object](/docs/resources/channel#channel-object) | Channel object with recipient information                                               |

### Passthrough Message Object

Represents a message between provisional users that exists only in-game.

###### Passthrough Message Structure

| Field          | Type                                                           | Description                                                                                                                             |
|----------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| id             | snowflake                                                      | ID of the message                                                                                                                       |
| type           | integer                                                        | [Type of message](/docs/resources/message#message-object-message-types)                                                                 |
| content        | string                                                         | Contents of the message                                                                                                                 |
| channel_id     | snowflake                                                      | ID of the channel the message was sent in                                                                                               |
| recipient_id   | snowflake                                                      | ID of the message recipient                                                                                                             |
| author         | [user object](/docs/resources/user#user-object-user-structure) | Author of the message                                                                                                                   |
| flags          | integer                                                        | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
| application_id | snowflake                                                      | ID of the application that created the message                                                                                          |
| channel        | [channel object](/docs/resources/channel#channel-object)       | Channel object with recipient information                                                                                               |

:::info
When both users in a direct message are provisional accounts, messages become "passthrough messages" that are only visible in-game and use this specialized structure.
:::
